ATSUOffsetToPosition

OSStatus ATSUOffsetToPosition (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iOffset,
                     Boolean iIsLeading,
                     ATSUCaret *oMainCaret,
                     ATSUCaret *oSecondCaret,
                     Boolean *oCaretIsSplit);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iOffset

A pointer to a value of type UniCharArrayOffset. Pass the edge offset whose corresponding caret position(s) you want to determine. If you wish to visually respond to a mouse-down event, pass the offset passed back in the ioPrimaryOffset parameter of the function ATSUPositionToOffset.

iIsLeading

A Boolean value. This value is only relevant if the edge offset is at a line direction boundary. Pass true if the edge offset is leading. In this case, it corresponds to the first offset of the line whose origin is specified in the iLocationX and iLocationY parameters. Pass false if the edge offset is trailing. In this case, it corresponds to the last offset of the line whose origin is specified in the iLocationX and iLocationY parameters. The last offset has a value equal to the sum of the starting edge offset and line length.

oMainCaret

A pointer to a structure of type ATSUCaret. On return, the structure contains the starting and ending pen locations of the high caret if the value passed back in oCaretIsSplit is true. If the passed back value is false, the structure contains the starting and ending pen locations of the main caret.

oSecondCaret

A pointer to a structure of type ATSUCaret. On return, the structure contains the starting and ending pen locations of the low caret if the value passed back in oCaretIsSplit is true. If the passed back value is false, the structure contains the starting and ending pen locations of the main caret (same as the oMainCaret parameter).

oCaretIsSplit

A pointer to a Boolean value. On return, the value indicates whether the edge offset specified in iOffset occurs at a line direction boundary. If true, the offset occurs at a line direction boundary; otherwise, false.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUOffsetToPosition function determines the caret position(s) that correspond to an edge offset.

The user expects that pressing the mouse button correlates to the display of a caret in text. Your application should call the ATSUOffsetToPosition function to find the caret position(s) corresponding to a mouse-down event.

To determine caret position(s), you must first pass the location of the mouse-down event to the function ATSUPositionToOffset. ATSUPositionToOffset passes back the edge offset (or offsets, if the hit occurs on a line direction boundary) from the beginning of the line where the hit occurred.

The offset passed back by ATSUPositionToOffset is relative to the beginning of the line in which the hit occurred, not from the beginning of the text layout object's buffer. Because this offset is a relative position, you must transform the starting and ending pen locations of the caret(s) that are passed back by ATSUOffsetToPosition before drawing them. The passed back carets do not need to be transformed to reflect angled and split caret appearances.

To do so, add the starting and ending caret coordinates to the coordinates of the origin of the line (in the current graphics port) in which the hit occurred. For example, if ATSUOffsettoPosition passed back the starting and ending pen locations of (25,0), (25,25) in the oMainCaret parameter (and the oSecondCaret parameter contained the same coordinates, meaning that the caret was not split), you would add these to the position of the origin of the line in the graphics port. If the position of the line origin was at (50,50), then the starting and ending pen locations of the caret on the screen would be (75,50), (75,75).

To draw the caret, you can call the QuickDraw functions MoveTo and LineTo, or equivalent functions.

SPECIAL CONSIDERATIONS

ATSUOffsetToPosition may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.